//+------------------------------------------------------------------+
//|                                                         ISet.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include "ICollection.h"  // 引入基础集合接口 ICollection<T>，继承其元素管理能力

//+------------------------------------------------------------------+
//| ISet<T> 泛型接口：MQL5 集合（Set）标准接口                        |
//| 核心定位：继承自基础集合接口 ICollection<T>，专注于“元素唯一”的集合管理， |
//|           提供集合间的数学运算（差集、交集、并集等）和关系判断（子集、超集等）能力，|
//|           为哈希集、树集等“无重复元素”的集合结构提供统一操作规范       |
//| 核心特性：元素唯一性（集合中不会存在重复元素，Add() 方法会自动忽略重复项），|
//|           不保证元素顺序（部分实现如树集可能有序，但接口不强制）         |
//| 核心价值：作为“数学集合”的抽象实现，解决需要管理唯一元素且需进行集合运算的场景，|
//|           如订单ID去重、权限集合交集计算、数据差异对比等，简化复杂集合操作 |
//| 与父接口关系：继承 ICollection<T> 的基础能力（Add/Count/Clear等），|
//|               新增集合特有的数学运算和关系判断方法，强化集合论操作能力   |
//| 适用场景：所有需要管理唯一元素且涉及集合运算的 MQL5 程序（EA、指标、脚本），|
//|           如订单去重管理、权限验证（角色权限与操作权限的交集）、数据同步（新旧数据差集）等 |
//+------------------------------------------------------------------+
template<typename T>
interface ISet : public ICollection<T>
  {
   //----------------------------------------------------------------
   // 集合差集运算：从当前集合中移除与目标集合共有的元素
   //----------------------------------------------------------------
   /**
    * @brief 计算当前集合与目标集合的差集（当前集合 = 当前集合 - 交集）
    * @param collection [in] 目标集合（ICollection<T> 实现类，如另一个 ISet）
    * @note 操作后，当前集合仅保留“自身有而目标集合没有”的元素
    *       示例：当前集合={1,2,3}，目标集合={2,3,4} → 结果={1}
    */
   void              ExceptWith(ICollection<T>* collection);

   /**
    * @brief 计算当前集合与目标数组的差集（功能同上，参数为数组）
    * @param array [in] 目标数组（元素类型为 T）
    */
   void              ExceptWith(T &array[]);

   //----------------------------------------------------------------
   // 集合交集运算：保留当前集合与目标集合的共有元素
   //----------------------------------------------------------------
   /**
    * @brief 计算当前集合与目标集合的交集（当前集合 = 交集）
    * @param collection [in] 目标集合
    * @note 操作后，当前集合仅保留“自身和目标集合都有”的元素
    *       示例：当前集合={1,2,3}，目标集合={2,3,4} → 结果={2,3}
    */
   void              IntersectWith(ICollection<T>* collection);

   /**
    * @brief 计算当前集合与目标数组的交集（功能同上，参数为数组）
    * @param array [in] 目标数组
    */
   void              IntersectWith(T &array[]);

   //----------------------------------------------------------------
   // 集合对称差集运算：保留仅在其中一个集合中存在的元素
   //----------------------------------------------------------------
   /**
    * @brief 计算当前集合与目标集合的对称差集（当前集合 = (A-B)∪(B-A)）
    * @param collection [in] 目标集合
    * @note 操作后，当前集合保留“仅自身有”或“仅目标集合有”的元素（排除共有元素）
    *       示例：当前集合={1,2,3}，目标集合={2,3,4} → 结果={1,4}
    */
   void              SymmetricExceptWith(ICollection<T>* collection);

   /**
    * @brief 计算当前集合与目标数组的对称差集（功能同上，参数为数组）
    * @param array [in] 目标数组
    */
   void              SymmetricExceptWith(T &array[]);

   //----------------------------------------------------------------
   // 集合并集运算：合并当前集合与目标集合的所有元素（去重）
   //----------------------------------------------------------------
   /**
    * @brief 计算当前集合与目标集合的并集（当前集合 = A∪B，自动去重）
    * @param collection [in] 目标集合
    * @note 操作后，当前集合包含“自身或目标集合中的所有元素”，重复元素仅保留一个
    *       示例：当前集合={1,2,3}，目标集合={2,3,4} → 结果={1,2,3,4}
    */
   void              UnionWith(ICollection<T>* collection);

   /**
    * @brief 计算当前集合与目标数组的并集（功能同上，参数为数组）
    * @param array [in] 目标数组
    */
   void              UnionWith(T &array[]);

   //----------------------------------------------------------------
   // 集合关系判断：当前集合是否为目标集合的真子集（子集且不相等）
   //----------------------------------------------------------------
   /**
    * @brief 判断当前集合是否为目标集合的真子集（A⊂B 且 A≠B）
    * @param collection [in] 目标集合
    * @return bool - 判断结果：true=是真子集；false=不是
    * @note 真子集要求：当前集合的所有元素都在目标集合中，且目标集合有额外元素
    *       示例：当前集合={1,2}，目标集合={1,2,3} → 返回 true
    */
   bool              IsProperSubsetOf(ICollection<T>* collection);

   /**
    * @brief 判断当前集合是否为目标数组的真子集（功能同上，参数为数组）
    * @param array [in] 目标数组
    * @return bool - 判断结果
    */
   bool              IsProperSubsetOf(T &array[]);

   //----------------------------------------------------------------
   // 集合关系判断：当前集合是否为目标集合的真超集（超集且不相等）
   //----------------------------------------------------------------
   /**
    * @brief 判断当前集合是否为目标集合的真超集（A⊃B 且 A≠B）
    * @param collection [in] 目标集合
    * @return bool - 判断结果：true=是真超集；false=不是
    * @note 真超集要求：目标集合的所有元素都在当前集合中，且当前集合有额外元素
    *       示例：当前集合={1,2,3}，目标集合={1,2} → 返回 true
    */
   bool              IsProperSupersetOf(ICollection<T>* collection);

   /**
    * @brief 判断当前集合是否为目标数组的真超集（功能同上，参数为数组）
    * @param array [in] 目标数组
    * @return bool - 判断结果
    */
   bool              IsProperSupersetOf(T &array[]);

   //----------------------------------------------------------------
   // 集合关系判断：当前集合是否为目标集合的子集（可相等）
   //----------------------------------------------------------------
   /**
    * @brief 判断当前集合是否为目标集合的子集（A⊆B，可与目标集合相等）
    * @param collection [in] 目标集合
    * @return bool - 判断结果：true=是子集；false=不是
    * @note 子集要求：当前集合的所有元素都在目标集合中（允许两者相等）
    *       示例：当前集合={1,2}，目标集合={1,2} → 返回 true
    */
   bool              IsSubsetOf(ICollection<T>* collection);

   /**
    * @brief 判断当前集合是否为目标数组的子集（功能同上，参数为数组）
    * @param array [in] 目标数组
    * @return bool - 判断结果
    */
   bool              IsSubsetOf(T &array[]);

   //----------------------------------------------------------------
   // 集合关系判断：当前集合是否为目标集合的超集（可相等）
   //----------------------------------------------------------------
   /**
    * @brief 判断当前集合是否为目标集合的超集（A⊇B，可与目标集合相等）
    * @param collection [in] 目标集合
    * @return bool - 判断结果：true=是超集；false=不是
    * @note 超集要求：目标集合的所有元素都在当前集合中（允许两者相等）
    *       示例：当前集合={1,2}，目标集合={1,2} → 返回 true
    */
   bool              IsSupersetOf(ICollection<T>* collection);

   /**
    * @brief 判断当前集合是否为目标数组的超集（功能同上，参数为数组）
    * @param array [in] 目标数组
    * @return bool - 判断结果
    */
   bool              IsSupersetOf(T &array[]);

   //----------------------------------------------------------------
   // 集合关系判断：当前集合与目标集合是否有交集
   //----------------------------------------------------------------
   /**
    * @brief 判断当前集合与目标集合是否存在共同元素（是否有交集）
    * @param collection [in] 目标集合
    * @return bool - 判断结果：true=存在共同元素；false=无交集
    *       示例：当前集合={1,2}，目标集合={2,3} → 返回 true
    */
   bool              Overlaps(ICollection<T>* collection);

   /**
    * @brief 判断当前集合与目标数组是否存在共同元素（功能同上，参数为数组）
    * @param array [in] 目标数组
    * @return bool - 判断结果
    */
   bool              Overlaps(T &array[]);

   //----------------------------------------------------------------
   // 集合关系判断：当前集合与目标集合是否完全相等
   //----------------------------------------------------------------
   /**
    * @brief 判断当前集合与目标集合是否包含完全相同的元素（忽略顺序）
    * @param collection [in] 目标集合
    * @return bool - 判断结果：true=元素完全相同；false=存在差异
    * @note 相等判定不依赖元素顺序，仅要求元素完全一致（数量和值均相同）
    *       示例：当前集合={1,2}，目标集合={2,1} → 返回 true
    */
   bool              SetEquals(ICollection<T>* collection);

   /**
    * @brief 判断当前集合与目标数组是否包含完全相同的元素（功能同上，参数为数组）
    * @param array [in] 目标数组
    * @return bool - 判断结果
    */
   bool              SetEquals(T &array[]);
  };
//+------------------------------------------------------------------+